组件系统

Gradio 提供了丰富的组件（Components），用于处理各种类型的输入和输出。这些组件是构建界面的基本构建块，可以帮助您创建交互式应用程序，处理从文本到图像、音频、视频等多种数据类型。

组件概述

Gradio 组件分为三大类：

输入组件：用于收集用户输入
输出组件：用于显示函数输出
辅助组件：提供额外功能，如标签、按钮等

大多数组件既可以作为输入也可以作为输出使用，但有些组件是专用的。

常用组件

文本类组件

Textbox (文本框)

python

gr.Textbox(
    value="默认文本",     # 默认值
    placeholder="请输入...", # 占位文本
    label="文本输入",     # 标签
    lines=1,            # 行数（1表示单行，>1表示多行）
    max_lines=20,       # 最大行数
    type="text"         # 类型 ("text", "password", "email")
)

Markdown

python

gr.Markdown("# 标题\n这是一段 **Markdown** 文本。")

Label (标签)

python

gr.Label(
    value={"类别1": 0.7, "类别2": 0.2, "类别3": 0.1},  # 分类结果
    num_top_classes=2,  # 显示前几个类别
    label="分类结果"
)

数值类组件

Number (数字)

python

gr.Number(
    value=0,           # 默认值
    label="数值输入",    # 标签
    precision=2,       # 精度（小数点后位数）
    minimum=-10,       # 最小值
    maximum=10,        # 最大值
    step=0.1           # 步长
)

Slider (滑块)

python

gr.Slider(
    minimum=0,         # 最小值
    maximum=100,       # 最大值
    value=50,          # 默认值
    step=1,            # 步长
    label="滑块",       # 标签
    info="调整值"       # 附加信息
)

选择类组件

Checkbox (复选框)

python

gr.Checkbox(
    value=False,       # 默认值
    label="启用选项",    # 标签
    info="选中以启用"    # 附加信息
)

Radio (单选按钮)

python

gr.Radio(
    choices=["选项1", "选项2", "选项3"],  # 选项列表
    value="选项1",                      # 默认值
    label="单选",                       # 标签
    info="选择一个选项"                  # 附加信息
)

python

gr.Dropdown(
    choices=["选项1", "选项2", "选项3"],  # 选项列表
    value="选项1",                      # 默认值
    label="下拉选择",                    # 标签
    multiselect=False,                 # 是否允许多选
    info="选择一个选项"                  # 附加信息
)

CheckboxGroup (复选框组)

python

gr.CheckboxGroup(
    choices=["选项1", "选项2", "选项3"],  # 选项列表
    value=["选项1"],                    # 默认选中的选项
    label="多选"                        # 标签
)

媒体类组件

Image (图像)

python

gr.Image(
    value=None,        # 默认图像
    shape=(224, 224),  # 图像尺寸 (高度, 宽度)
    source="upload",   # 来源，"upload"、"webcam"或"canvas"
    tool="editor",     # 工具，"editor", "select", "sketch", 或 None
    type="numpy",      # 返回类型，"numpy", "pil", "filepath"
    label="图像"        # 标签
)

Audio (音频)

python

gr.Audio(
    value=None,        # 默认音频
    source="upload",   # 来源，"upload", "microphone", 或 None
    type="numpy",      # 返回类型，"numpy", "filepath"
    label="音频"        # 标签
)

Video (视频)

python

gr.Video(
    value=None,        # 默认视频
    format="mp4",      # 格式
    label="视频"        # 标签
)

数据结构组件

Dataframe (数据表格)

python

gr.Dataframe(
    value=None,                            # 默认数据
    headers=["列1", "列2", "列3"],          # 列标题
    row_count=(1, 5),                      # (最小行数, 最大行数)
    col_count=(3, 3),                      # (最小列数, 最大列数)
    datatype=["str", "number", "bool"],    # 列数据类型
    label="数据表"                          # 标签
)

JSON (JSON数据)

python

gr.JSON(
    value={"key": "value"},  # 默认值
    label="JSON数据"          # 标签
)

文件类组件

File (文件)

python

gr.File(
    value=None,              # 默认文件
    file_types=[".pdf", ".txt"],  # 允许的文件类型
    file_count="single",     # "single" 或 "multiple"
    label="上传文件"           # 标签
)

特殊类组件

Button (按钮)

python

gr.Button(
    value="点击",         # 按钮文本
    variant="primary",   # 样式，"primary", "secondary", "stop"等
    size="sm",           # 大小，"sm", "md", "lg"
    interactive=True,    # 是否可交互
    visible=True         # 是否可见
)

Plot (绘图)

python

gr.Plot(
    value=None,   # matplotlib 图形或其他支持的图形对象
    label="图表"   # 标签
)

组件属性和方法

大多数 Gradio 组件共享以下属性和方法：

常用属性

label: 组件标签
value: 组件当前值
visible: 组件是否可见
interactive: 组件是否可交互

常用方法

update(): 更新组件属性
style(): 设置组件样式
change(), click() 等事件方法: 用于设置事件处理器

使用 update() 方法

update() 方法是动态修改组件属性的关键。例如：

python

import gradio as gr

def update_textbox(value):
    return gr.Textbox.update(value=value, label="更新后的标签")

with gr.Blocks() as demo:
    input_text = gr.Textbox(label="输入")
    output_text = gr.Textbox(label="输出")
    button = gr.Button("更新")
    
    button.click(update_textbox, inputs=input_text, outputs=output_text)

demo.launch()

组件交互模式

组件可以设置为三种交互模式：

交互式 (interactive=True): 用户可以编辑和修改
静态 (interactive=False): 用户不能修改，只能查看
不可见 (visible=False): 组件完全隐藏

python

gr.Textbox(interactive=True)   # 用户可以编辑
gr.Textbox(interactive=False)  # 用户只能查看，不能编辑
gr.Textbox(visible=False)      # 组件不可见

组件样式定制

您可以使用 style() 方法或 CSS 类来定制组件外观：

python

gr.Textbox().style(
    container=False,           # 是否显示容器
    rounded=(True, True, True, True),  # 四个角是否圆角
    border_color="red",        # 边框颜色
    color_mode="primary"       # 颜色模式
)

组件状态与其他组件的关系

组件可以根据其他组件的状态动态更新：

python

def update_components(choice):
    if choice == "图像":
        return gr.Image.update(visible=True), gr.Audio.update(visible=False)
    else:
        return gr.Image.update(visible=False), gr.Audio.update(visible=True)

with gr.Blocks() as demo:
    choice = gr.Radio(["图像", "音频"], label="选择组件")
    image = gr.Image(visible=False)
    audio = gr.Audio(visible=False)
    
    choice.change(update_components, inputs=choice, outputs=[image, audio])

自定义组件

Gradio 允许您创建自定义组件，扩展其内置功能。一个基本的自定义组件需要实现以下方法：

python

import gradio as gr

class MyCustomComponent(gr.Component):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.value = kwargs.get("value", None)
        
    def preprocess(self, x):
        # 将组件值转换为函数输入
        return x
        
    def postprocess(self, y):
        # 将函数输出转换为组件值
        return y
        
    def get_template_context(self):
        # 返回渲染组件所需的上下文
        return {
            "value": self.value,
            "label": self.label,
            # 其他属性
        }

组件事件

Gradio 组件可以触发多种事件：

click: 点击事件（按钮等）
change: 值改变事件（文本框、滑块等）
submit: 提交事件（文本框、表单等）
focus: 获得焦点事件
blur: 失去焦点事件

以下是一个使用多种事件的示例：

python

def on_change(value):
    return f"值改变为: {value}"

def on_submit(value):
    return f"提交值: {value}"

def on_focus():
    return "获得焦点"

def on_blur():
    return "失去焦点"

with gr.Blocks() as demo:
    text = gr.Textbox(label="输入")
    change_out = gr.Textbox(label="change 事件")
    submit_out = gr.Textbox(label="submit 事件")
    focus_out = gr.Textbox(label="focus 事件")
    blur_out = gr.Textbox(label="blur 事件")
    
    text.change(on_change, text, change_out)
    text.submit(on_submit, text, submit_out)
    text.focus(on_focus, None, focus_out)
    text.blur(on_blur, None, blur_out)

组件最佳实践

选择合适的组件类型：根据数据类型和用户交互需求选择最合适的组件。
提供清晰的标签和说明：使用 label 和 info 参数帮助用户理解组件的用途。
设置适当的默认值：为组件提供合理的默认值，减少用户输入负担。
限制输入范围：使用 minimum, maximum, choices 等参数限制用户输入的有效范围。
利用组件事件：使用 change, click 等事件来创建响应式界面。
动态更新组件：使用 update() 方法根据用户交互动态修改组件属性。
注意组件的状态管理：使用 gr.State 在会话中存储不需要显示的数据。

组件技巧与示例

条件显示

根据选择显示/隐藏其他组件：

python

def update_visibility(show_extra):
    return gr.update(visible=show_extra)

with gr.Blocks() as demo:
    checkbox = gr.Checkbox(label="显示高级选项")
    with gr.Group(visible=False) as advanced:
        slider = gr.Slider(1, 10, label="高级参数")
    
    checkbox.change(update_visibility, inputs=checkbox, outputs=advanced)

动态选项

根据一个下拉菜单的选择更新另一个下拉菜单的选项：

python

def update_options(category):
    options = {
        "水果": ["苹果", "香蕉", "橙子"],
        "蔬菜": ["黄瓜", "西红柿", "胡萝卜"],
        "肉类": ["牛肉", "猪肉", "鸡肉"]
    }
    return gr.Dropdown.update(choices=options[category])

with gr.Blocks() as demo:
    category = gr.Dropdown(["水果", "蔬菜", "肉类"], label="类别")
    items = gr.Dropdown([], label="具体项目")
    
    category.change(update_options, inputs=category, outputs=items)

组件链式更新

多个组件间的连锁更新：

python

def convert_temperature(celsius, unit):
    if unit == "华氏度":
        return f"{celsius * 9/5 + 32} °F"
    elif unit == "开尔文":
        return f"{celsius + 273.15} K"
    else:
        return f"{celsius} °C"

with gr.Blocks() as demo:
    celsius = gr.Slider(0, 100, 25, label="摄氏度")
    unit = gr.Radio(["摄氏度", "华氏度", "开尔文"], value="摄氏度", label="转换单位")
    output = gr.Textbox(label="结果")
    
    # 温度或单位改变时更新结果
    celsius.change(convert_temperature, inputs=[celsius, unit], outputs=output)
    unit.change(convert_temperature, inputs=[celsius, unit], outputs=output)

总结

Gradio 组件是构建交互式应用程序的基础，它们提供了丰富的功能来处理各种类型的数据和用户交互。通过合理组合组件、设置事件处理、管理组件状态等技术，您可以创建功能强大且用户友好的界面。

每种组件都有其特定的用途和配置选项，深入了解这些组件的属性和方法可以帮助您更有效地构建应用程序。在后续的章节中，我们将探讨如何将这些组件与 Interface 和 Blocks API 结合使用，创建更复杂的应用程序。

组件系统 ​

组件概述 ​

常用组件 ​

文本类组件 ​

Textbox (文本框) ​

Markdown ​

Label (标签) ​

数值类组件 ​

Number (数字) ​

Slider (滑块) ​

选择类组件 ​

Checkbox (复选框) ​

Radio (单选按钮) ​

Dropdown (下拉列表) ​

CheckboxGroup (复选框组) ​

媒体类组件 ​

Image (图像) ​

Audio (音频) ​

Video (视频) ​

数据结构组件 ​

Dataframe (数据表格) ​

JSON (JSON数据) ​

文件类组件 ​

File (文件) ​

特殊类组件 ​

Button (按钮) ​

Plot (绘图) ​

组件属性和方法 ​

常用属性 ​

常用方法 ​

使用 update() 方法 ​

组件交互模式 ​

组件样式定制 ​

组件状态与其他组件的关系 ​

自定义组件 ​

组件事件 ​

组件最佳实践 ​

组件技巧与示例 ​

条件显示 ​

动态选项 ​

组件链式更新 ​

总结 ​

组件系统

组件概述

常用组件

文本类组件

Textbox (文本框)

Markdown

Label (标签)

数值类组件

Number (数字)

Slider (滑块)

选择类组件

Checkbox (复选框)

Radio (单选按钮)

Dropdown (下拉列表)

CheckboxGroup (复选框组)

媒体类组件

Image (图像)

Audio (音频)

Video (视频)

数据结构组件

Dataframe (数据表格)

JSON (JSON数据)

文件类组件

File (文件)

特殊类组件

Button (按钮)

Plot (绘图)

组件属性和方法

常用属性

常用方法

使用 update() 方法

组件交互模式

组件样式定制

组件状态与其他组件的关系

自定义组件

组件事件

组件最佳实践

组件技巧与示例

条件显示

动态选项

组件链式更新

总结